AI 上下文膨胀问题

问题：

• 由于近期在项目中大量使用 claude code，积累了一些上下文规则，包括项目术语、git 提交规则、文档子项目和插件子项目相关的规则等，导致 CLAUDE.md 日渐臃肿；token 消耗大幅增加；
• docs 子项目目前已经提交 130+ 个文档，会作为 AI 上下文使用，有时会要求 AI 直接检索 docs 子项目以筛选信息，导致 AI 处理任务时耗时、消耗 Tokens 数爆炸式增长（虽然 Claude Code 检索本地文档是在本地进行）；

‍

尝试优化：

失败尝试：模块化 + 标注系统 + @导入、文件索引

方案设计：

# CLAUDE.md
.....

### 主项目 (WTC)
- **核心规则**: [必读] @docs/工程-工具/ai-rules/WTC/core-rules.md
- **Git 提交**: [触发提交任务时-必读] `docs/工程-工具/ai-rules/WTC/git-commits.md`
- **Shell 脚本**: [编写脚本时-必读] `docs/工程-工具/ai-rules/WTC/shell-scripts.md`
- **配置同步**: [修改配置时-强制] `docs/工程-工具/ai-rules/WTC/config-sync.md`

.....

标注系统：

• ​[必读] - 启动时必读
• ​[XX任务时-必读] - 特定任务触发
• ​[强制] - 必须严格遵守
• 无标注 - 可选参考

思路：

• 模块化，拆分出不同的上下文、规则文档
• 通过标注告诉 AI 何时读取
• CLAUDE.md 仅作索引,具体规则文件放到 docs 子项目集中管理

验证： ​[Claude Code 模块化拆分+标注机制实验报告](/../工程-工具/AI/Claude Code 模块化拆分+标注机制实验报告)

结论：标注系统无效，❌ 即使标注 [必读]，新的 AI 实例依然无法主动读取链接文档

CLAUDE.md 是一个静态的 Markdown 文件，Claude Code 会：

1. 读取整个文件内容

2. 作为系统上下文注入

3. 不解析任何特殊语法（如 @、[[]] 等）

   奇怪的是，AI 能够理解加粗文字是着重强调的意思

---

优化方案：

🧾 一、明确划分 CLAUDE.md

• CLAUDE.md 应该包含什么？

  官方定义:
  "This file provides context and guidance to Claude Code when working with code in this repository."

  关键词: Context（上下文）+ Guidance（指导）

• 两种内容类型

  1️⃣ 信息/上下文（Information/Context）

  2️⃣ 规则/指令（Rules/Instructions）

• 划分板块

  1. 📚 Context（上下文）
  2. ⚠️ Rules（规则）
  3. 🤖 Decision（决策）

‍

🎯 二、制定三层规则架构

第一层: 核心规则（CLAUDE.md 内联）

• 可靠性要求：100%

  违反后果严重，恢复困难；

• 载入方式：

  AI 实例启动时、自动载入；（100% 载入）

• 示例：

  Git 错误提交 → 污染历史记录，难以撤销 → 必须内联

第二层: 附加、详细规则（外部文件 + 引导）

• 可靠性要求：~85%

  1. 违反后果可直接验证，恢复容易
  2. 复杂任务的补充规则、上下文,没有也不影响最终任务结果

• 存储位置: docs/工程-工具/ai-rules/

• 载入方式：

  AI 检查 CLAUDE.md 中的"任务触发规则表" → 匹配关键词 → 读取规则文件
  （半自动，依赖 AI 判断，~85% 可靠）

• 适用场景：

  1. 详细规则（第一层已有核心要求，这里是补充细节）
  2. 复杂流程（如多项目提交、冲突处理）
  3. 参考规范（如 Shell 脚本最佳实践）

• 示例：

  • Shell 脚本完整规范 → 核心规则已有基础要求，详细规范包含错误处理、日志等
  • Git 多项目提交流程 → 核心规则已要求确认，详细规范包含提交顺序、冲突处理
  • VitePress 链接格式 → 核心规则已禁止相对链接，详细规范包含处理流程

第三层: 复杂任务（Slash Commands）

• 可靠性要求: 100%（用户主动触发）

• 存储位置： .claude/commands/

• 载入方式：

  自定义 claude 斜杠命令，需要时手动输入斜杠命令载入；

• 适用场景：

  1. 用户明确知道要做什么
  2. 任务有明确的起止
  3. 需要完整上下文、多文档成组载入
  4. 需要完整的工作流程（多步骤、多检查点）
  5. 特殊知识体系

  类型	说明	工作边界	示例
  系统化任务	有明确执行清单	检查开始 → 检查完成	关卡生成、开发
  工作模块	特定领域完整规则	进入模块 → 离开模块	插件开发
  业务流程	有明确边界的业务	流程开始 → 流程结束	活动换皮

‍

📊 三、AI 决策引导

• 添加工作流程引导

  • 明确任务执行过程：基础、重要的规则直接内联，明确执行过程
  • 添加规则索引表：

  

  

• 添加规则维护引导

  

  

AI 上下文文档瘦身：

• 简洁、具体 - 直击要点，避免模糊表述
• 使用子弹点 - 列表 > 表格 > 代码块
• 指令至上 - 避免解释性文字

‍

结尾思考

• 如果 CLAUDE.md 记录出现错误信息、过时信息、甚至只是因为信息不够精确，AI 都很可能会陷入误区并且难以脱离，如何保证 CLAUDE.md 持久有效？

• 当我们主动干预、给出改进意见时，AI 往往会妥协并按照新的干预方向去思考；但干预方向很可能是错的，最终的执行结果偏离预期，浪费时间；

• 小趣事：Claude Code 无法处理包含最近更新字样的需求